Skip to content

Use FORWARDREF format in inspect.signature calls #13946

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Use FORWARDREF format in inspect.signature calls #13946

wants to merge 1 commit into from
+65 −3

Conversation

ruipin
Copy link

@ruipin ruipin commented Oct 10, 2025

Fixes #13945

Purpose

Python 3.14 adds the annotationlib module, as well as the annotation_format keyword parameter to inspect.signature.
Passing annotation_format=annotationlib.Format.FORWARDREF to inspect.signature calls allows us to support Python 3.14 forward references in annotations robustly, fixing the current issues described in #13945

References

Fixes #13945

@Copilot Copilot AI review requested due to automatic review settings October 10, 2025 15:15
Copilot
Copilot AI reviewed Oct 10, 2025
View reviewed changes
Copy link

@Copilot Copilot AI left a comment •
edited by AA-Turner
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

spam

@ruipin ruipin mentioned this pull request Oct 10, 2025
Open
@ruipin
Copy link
Author

ruipin commented Oct 10, 2025

Hmm, seems mypy does not like annotationlib being imported at all, probably because it is exclusive to Python 3.14+.
I added # type: ignore[import-not-found], not sure if there is a better way to resolve this?

AA-Turner
AA-Turner reviewed Oct 10, 2025
View reviewed changes
sphinx/util/inspect.py Outdated
Comment on lines 719 to 727
# Python 3.14 added the annotationlib module to the standard library as well as the
# 'annotation_format' keyword parameter to inspect.signature(), which allows us to handle
# forward references more robustly.
try:
import annotationlib # type: ignore[import-not-found]

inspect_signature_extra = {'annotation_format': annotationlib.Format.FORWARDREF}
except ImportError:
inspect_signature_extra = {}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be a module global, instead of being computed each time. Also, prefer using sys.version checks.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved inspect_signature_extra to the module scope and am now checking sys.version_info instead of try/except ImportError. Does this look acceptable?

See https://github.com/sphinx-doc/sphinx/pull/13946/files#diff-c0bc794b755edda6e5e4681048737461d878ca58c4cbffc8ceb0dd6512d6d07fR78-R83

AA-Turner
AA-Turner requested changes Oct 10, 2025
View reviewed changes
Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a test and CHANGES entry, and consider listing yourself in AUTHORS.

A

@ruipin ruipin force-pushed the master branch 3 times, most recently from fb8ced5 to e6d722c Compare October 10, 2025 15:51
@ruipin
Copy link
Author

ruipin commented Oct 10, 2025 •
edited
Loading

I've now moved the inspect_signature_extra dictionary to module scope as discussed. Let me know if you'd like any further changes.

Added forward reference tests to test_util_inspect.py which test the usage of forward references. However, because this file uses from __futures__ import annotations which prevents the issue from being reproducible, I also created a new file test_util_inspect_py314.py which is only executed when the python version is >= 3.14, and does not use from __future__ import annotations.

Using python 3.14, without the bug fix this new test (test_util_inspect_py314.py:test_signature_forwardref) fails. With the fix, the new test passes.

Also fixed the lint issues, updated CHANGES, and added myself to AUTHORS.

Hopefully everything looks good, happy to do further changes though, just let me know.

@ruipin ruipin requested a review from AA-Turner October 10, 2025 15:59
@ruipin ruipin mentioned this pull request Oct 13, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@AA-Turner AA-Turner Awaiting requested review from AA-Turner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

sphinx.ext.autodoc: Broken Python 3.14 forward references support

2 participants

@ruipin @AA-Turner